<h1>Action Controllers</h1>

<h2>Introduction</h2>

<p>Action controllers are "controller" part of <a href="http://en.wikipedia.org/wiki/Model-view-controller">Model-View-Controller</a> [wikipedia.org].  They are loaded by the <a href="?p=4/Front_Controller">Front Controller</a> when a request to the bootstrap is made.  Every action controller must have at least one action.  An action is simply a method in the action controller class.  Here is an example action controller:</p>

<pre class="prettyprint lang-php">class foobar extends A_Controller_Action {

	public function index($locator) {
		// the default action
	}
	
	public function foo($locator) {
		// do something else
	}
	
	public function _bar() {
		// can't touch 'dis
	}

}
</pre>

<p>The first thing you probably notice is that the class extends the class A_Controller_Action.  That's not necessary, but it does provide several conveniences.  The comes from Skeleton's philosophy.</p>

<p class="devnote">Provide link to skeleton's philosophy</p>

<p>Each action is given the <a href="?p=4/Locator">Locator</a> object that was passed to the <a href="?p=4/Front_Controller">Front Controller</a>.  This provides access to anything inside of the <a href="?p=4/Locator">Locator</a>, including the <a href="?p=4/Request">Request</a> and <a href="?p=4/Views">Response</a> objects, and anything else that was placed inside of it (e.g. Database connection, etc.).</p>

<p>If you create a method called index(), that will be used as the default action if no action is defined in the request.  Tip: you can easily redirect the default action to another action by calling that method, passing the $locator argument.</p>

<p>Any method that begins with an underscore <em>cannot</em> be dispatched to.  This means that it cannot be used as an action.  This means you can create a method not meant to be dispatched to, without making it private.</p>

<h2>Forwarding</h2>

<p class="devnote">Describe forwarding array</p>

<h2>Customization</h2>

<p>Many things laid out here can be customized with A_Controller_Mapper.  See the documentation on <a href="?p=4/Mapper">Mapper</a>.</p>

<h2>Extending A_Controller_Action</h2>

<p>Extending A_Controller_Action is handy, but by no means necessary.  Here are some of the benifits:</p>

<h3>Convenience Access</h3>

<p>A_Controller_Action provides quick access to often-used items.  For example, the <a href="?p=4/Request">Request</a> and <a href="?p=4/Views">Response</a> objects can be accessed from within an action with $this->request and $this->response, respectively.  It also gives quick access to the controller Load helper with the _load() method ($this->_load()).  Note that $this->request and $this->response will not be accessible unless the constructor is called with the Locator, either by not defining a constructor (as in the example above) or with parent::__construct($locator).</p>

<p>_request() is a quick way to get a value from the <a href="?p=4/Request">Request</a> object, and _response() will set values to the <a href="?p=4/Views">Response</a> object.</p>

<h3>Other Methods</h3>

<ul>
	<li>_redirect(): outputs a HTTP Locator header to redirect to another URL.</li>
	<li>_forward(): creates a forwarding array</li>
</ul>

<p>For the full list, see the <a href="http://skeletonframework.com/documentation/api/index.html">PHPDocs</a>.</p>

<h2>Other Options</h2>

<p>Either extending A_Controller_Action or not is not your only option.  You can extend your own class to consolidate code common among controllers, or one of Skeleton's other controller classes.</p>

<p class="devnote">List other specialty classes that can be extended</p>
